/*
 * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

package org.eclipse.imagen.operator;

import java.awt.RenderingHints;
import java.awt.image.RenderedImage;
import java.awt.image.SampleModel;
import java.awt.image.renderable.ParameterBlock;
import java.awt.image.renderable.RenderableImage;
import org.eclipse.imagen.JAI;
import org.eclipse.imagen.OperationDescriptorImpl;
import org.eclipse.imagen.ParameterBlockJAI;
import org.eclipse.imagen.RenderableOp;
import org.eclipse.imagen.RenderedOp;
import org.eclipse.imagen.registry.RenderableRegistryMode;
import org.eclipse.imagen.registry.RenderedRegistryMode;

/**
 * An <code>OperationDescriptor</code> describing the "Composite" operation.
 *
 * <p>The "Composite" operation combines two images based on their alpha values at each pixel. It is done on a per-band
 * basis, and the two source images are expected to have the same number of bands and the same data type. The
 * destination image has the same data type as the two sources.
 *
 * <p>The <code>destAlpha</code> parameter indicates if the destination image should have an extra alpha channel. If
 * this parameter is set to <code>NO_DESTINATION_ALPHA</code>, then the destination image does not include an alpha
 * band, and it should have the same number of bands as the two source images. If it is set to <code>
 * DESTINATION_ALPHA_FIRST</code>, then the destination image has one extra band than the source images, which
 * represents the result alpha channel, and this band is the first band (band 0) of the destination. If it is set to
 * <code>DESTINATION_ALPHA_LAST</code>, then the destination image also has the extra alpha channel, but this band is
 * the last band of the destination.
 *
 * <p>The destination pixel values may be viewed as representing a fractional pixel coverage or transparency factor.
 * Specifically, Composite implements the Porter-Duff "over" rule (see <i>Computer Graphics</i>, July 1984 pp. 253-259),
 * in which the output color of a pixel with source value/alpha tuples <code>(A, a)</code> and <code>(B, b)</code> is
 * given by <code>a*A + (1 - a)*(b*B)</code>. The output alpha value is given by <code>a + (1 - a)*b</code>. For
 * premultiplied sources tuples <code>(a*A, a)</code> and <code>(b*B, b)</code>, the premultiplied output value is
 * simply <code>(a*A) + (1 - a)*(b*B)</code>.
 *
 * <p>The color channels of the two source images are supplied via <code>source1</code> and <code>source2</code>. The
 * two sources must be either both pre-multiplied by alpha or not. Alpha channel should not be included in <code>source1
 * </code> and <code>source2</code>.
 *
 * <p>The alpha channel of the first source images must be supplied via the <code>source1Alpha</code> parameter. This
 * parameter may not be null. The alpha channel of the second source image may be supplied via the <code>source2Alpha
 * </code> parameter. This parameter may be null, in which case the second source is considered completely opaque. The
 * alpha images should be single-banded, and have the same data type as well as dimensions as their corresponding source
 * images.
 *
 * <p>The <code>alphaPremultiplied</code> parameter indicates whether or not the supplied alpha image is premultiplied
 * to both the source images. It also indicates whether the destination image color channels have the alpha values
 * multiplied to the pixel color values.
 *
 * <p>It should be noted that the <code>source1Alpha</code> and <code>source1Alpha</code> parameters are <code>
 * RenderedImage</code>s in the "rendered" mode and are <code>RenderableImage</code>s in the "renderable" mode.
 *
 * <p>The destination image is the combination of the two source images. It has the color channels, and if specified,
 * one additional alpha channel (the band index depends on the value of the <code>destAlpha</code> parameter). Whether
 * alpha value is pre-multiplied to the color channels also depend on the value of <code>alphaPremultiplied</code>
 * (pre-multiplied if true).
 *
 * <p>
 *
 * <table border=1>
 * <caption>Resource List</caption>
 * <tr><th>Name</th>        <th>Value</th></tr>
 * <tr><td>GlobalName</td>  <td>composite</td></tr>
 * <tr><td>LocallName</td>  <td>composite</td></tr>
 * <tr><td>Vendor</td>      <td>org.eclipse.imagen.media</td></tr>
 * <tr><td>Description</td> <td>Composites two images based on an alpha mask.</td></tr>
 * <tr><td>DocURL</td>      <td>http://java.sun.com/products/java-media/jai/forDevelopers/jaiapi/org.eclipse.imagen.operator.CompositeDescriptor.html</td></tr>
 * <tr><td>Version</td>     <td>1.0</td></tr>
 * <tr><td>arg0Desc</td>    <td>The alpha image for the first source.</td></tr>
 * <tr><td>arg1Desc</td>    <td>The alpha image for the second source.</td></tr>
 * <tr><td>arg2Desc</td>    <td>True if alpha has been premultiplied to both
 *                              sources and the destination.</td></tr>
 * <tr><td>arg3Desc</td>    <td>Indicates if the destination image should
 *                              include an extra alpha channel, and if so,
 *                              should it be the first or last band.</td></tr>
 * </table>
 *
 * <p>
 *
 * <table border=1>
 * <caption>Parameter List</caption>
 * <tr>
 *     <th>Name</th>
 *     <th COLSPAN=2>Class Type</th>
 *     <th>Default Value</th>
 * </tr>
 * <tr>
 *     <td ROWSPAN=2>source1Alpha</td>
 *     <td>Rendered mode</td>
 *     <td>java.awt.image.RenderedImage</td>
 *     <td ROWSPAN=2>NO_PARAMETER_DEFAULT</td>
 * </tr>
 * <tr>
 *     <td>Renderable mode</td>
 *     <td>java.awt.image.renderable.RenderableImage</td>
 * </tr>
 * <tr>
 *     <td ROWSPAN=2>source2Alpha</td>
 *     <td>Rendered mode</td>
 *     <td>java.awt.image.RenderedImage</td>
 *     <td ROWSPAN=2>null</td>
 * </tr>
 * <tr>
 *     <td>Renderable mode</td>
 *     <td>java.awt.image.renderable.RenderableImage</td>
 * </tr>
 * <tr>
 *     <td>alphaPremultiplied</td>
 *     <td COLSPAN=2>java.lang.Boolean</td>
 *     <td>false</td>
 * </tr>
 * <tr>
 *     <td>destAlpha</td>
 *     <td COLSPAN=2>org.eclipse.imagen.operator.CompositeDestAlpha</td>
 *     <td>NO_DESTINATION_ALPHA</td>
 * </tr>
 * </table>
 *
 * @see CompositeDestAlpha
 * @see java.awt.image.ColorModel
 * @see org.eclipse.imagen.OperationDescriptor
 */
public class CompositeDescriptor extends OperationDescriptorImpl {

    /** The destination image does not have the alpha channel. */
    public static final CompositeDestAlpha NO_DESTINATION_ALPHA = new CompositeDestAlpha("NO_DESTINATION_ALPHA", 0);

    /** The destination image has the channel, and it is the first band. */
    public static final CompositeDestAlpha DESTINATION_ALPHA_FIRST =
            new CompositeDestAlpha("DESTINATION_ALPHA_FIRST", 1);

    /** The destination image has the channel, and it is the last band. */
    public static final CompositeDestAlpha DESTINATION_ALPHA_LAST = new CompositeDestAlpha("DESTINATION_ALPHA_LAST", 2);

    /**
     * The resource strings that provide the general documentation and specify the parameter list for this operation.
     */
    protected static final String[][] resources = {
        {"GlobalName", "Composite"},
        {"LocalName", "Composite"},
        {"Vendor", "org.eclipse.imagen.media"},
        {"Description", JaiI18N.getString("CompositeDescriptor0")},
        {
            "DocURL",
            "http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/CompositeDescriptor.html"
        },
        {"Version", JaiI18N.getString("DescriptorVersion2")},
        {"arg0Desc", JaiI18N.getString("CompositeDescriptor1")},
        {"arg1Desc", JaiI18N.getString("CompositeDescriptor2")},
        {"arg2Desc", JaiI18N.getString("CompositeDescriptor3")},
        {"arg3Desc", JaiI18N.getString("CompositeDescriptor4")}
    };

    private static final Class[][] sourceClasses = {
        {java.awt.image.RenderedImage.class, java.awt.image.RenderedImage.class},
        {java.awt.image.renderable.RenderableImage.class, java.awt.image.renderable.RenderableImage.class}
    };

    /** The parameter class list for this operation. */
    private static final Class[][] paramClasses = {
        {
            java.awt.image.RenderedImage.class,
            java.awt.image.RenderedImage.class,
            java.lang.Boolean.class,
            CompositeDestAlpha.class
        },
        {
            java.awt.image.renderable.RenderableImage.class,
            java.awt.image.renderable.RenderableImage.class,
            java.lang.Boolean.class,
            CompositeDestAlpha.class
        }
    };

    /** The parameter name list for this operation. */
    private static final String[] paramNames = {
        "source1Alpha", "source2Alpha",
        "alphaPremultiplied", "destAlpha"
    };

    /** The parameter default value list for this operation. */
    private static final Object[][] paramDefaults = {
        {NO_PARAMETER_DEFAULT, null, Boolean.FALSE, NO_DESTINATION_ALPHA},
        {NO_PARAMETER_DEFAULT, null, Boolean.FALSE, NO_DESTINATION_ALPHA}
    };

    private static final String[] supportedModes = {"rendered", "renderable"};

    /** Constructor. */
    public CompositeDescriptor() {
        super(resources, supportedModes, null, sourceClasses, paramNames, paramClasses, paramDefaults, null);
    }

    /**
     * Validates the input sources and parameters.
     *
     * <p>In addition to the standard checks performed by the superclass method, this method checks that the source
     * image <code>samplemodel</code>s have the same number of bands and transfer type, and that the alpha images have
     * the same bounds as the corresponding sources and the correct transfer type.
     */
    public boolean validateArguments(String modeName, ParameterBlock args, StringBuffer msg) {
        if (!super.validateArguments(modeName, args, msg)) {
            return false;
        }

        if (!modeName.equalsIgnoreCase("rendered")) return true;

        RenderedImage src1 = args.getRenderedSource(0);
        RenderedImage src2 = args.getRenderedSource(1);

        SampleModel s1sm = src1.getSampleModel();
        SampleModel s2sm = src2.getSampleModel();
        if (s1sm.getNumBands() != s2sm.getNumBands() || s1sm.getTransferType() != s2sm.getTransferType()) {
            msg.append(getName() + " " + JaiI18N.getString("CompositeDescriptor8"));
            return false;
        }

        /* Validate Parameters. */
        RenderedImage afa1 = (RenderedImage) args.getObjectParameter(0);
        if (src1.getMinX() != afa1.getMinX()
                || src1.getMinY() != afa1.getMinY()
                || src1.getWidth() != afa1.getWidth()
                || src1.getHeight() != afa1.getHeight()) {
            msg.append(getName() + " " + JaiI18N.getString("CompositeDescriptor12"));
            return false;
        }

        SampleModel a1sm = afa1.getSampleModel();
        if (s1sm.getTransferType() != a1sm.getTransferType()) {
            msg.append(getName() + " " + JaiI18N.getString("CompositeDescriptor13"));
            return false;
        }

        RenderedImage afa2 = (RenderedImage) args.getObjectParameter(1);
        if (afa2 != null) {
            if (src2.getMinX() != afa2.getMinX()
                    || src2.getMinY() != afa2.getMinY()
                    || src2.getWidth() != afa2.getWidth()
                    || src2.getHeight() != afa2.getHeight()) {
                msg.append(getName() + " " + JaiI18N.getString("CompositeDescriptor15"));
                return false;
            }

            SampleModel a2sm = afa2.getSampleModel();
            if (s2sm.getTransferType() != a2sm.getTransferType()) {
                msg.append(getName() + " " + JaiI18N.getString("CompositeDescriptor16"));
                return false;
            }
        }

        return true;
    }

    /**
     * Composites two images based on an alpha mask.
     *
     * <p>Creates a <code>ParameterBlockJAI</code> from all supplied arguments except <code>hints</code> and invokes
     * {@link JAI#create(String,ParameterBlock,RenderingHints)}.
     *
     * @see JAI
     * @see ParameterBlockJAI
     * @see RenderedOp
     * @param source0 <code>RenderedImage</code> source 0.
     * @param source1 <code>RenderedImage</code> source 1.
     * @param source1Alpha The alpha image for the first source.
     * @param source2Alpha The alpha image for the second source. May be <code>null</code>.
     * @param alphaPremultiplied True if alpha has been premultiplied to both sources and the destination. May be <code>
     *     null</code>.
     * @param destAlpha Indicates if the destination image should include an extra alpha channel, and if so, should it
     *     be the first or last band. May be <code>null</code>.
     * @param hints The <code>RenderingHints</code> to use. May be <code>null</code>.
     * @return The <code>RenderedOp</code> destination.
     * @throws IllegalArgumentException if <code>source0</code> is <code>null</code>.
     * @throws IllegalArgumentException if <code>source1</code> is <code>null</code>.
     * @throws IllegalArgumentException if <code>source1Alpha</code> is <code>null</code>.
     */
    public static RenderedOp create(
            RenderedImage source0,
            RenderedImage source1,
            RenderedImage source1Alpha,
            RenderedImage source2Alpha,
            Boolean alphaPremultiplied,
            CompositeDestAlpha destAlpha,
            RenderingHints hints) {
        ParameterBlockJAI pb = new ParameterBlockJAI("Composite", RenderedRegistryMode.MODE_NAME);

        pb.setSource("source0", source0);
        pb.setSource("source1", source1);

        pb.setParameter("source1Alpha", source1Alpha);
        pb.setParameter("source2Alpha", source2Alpha);
        pb.setParameter("alphaPremultiplied", alphaPremultiplied);
        pb.setParameter("destAlpha", destAlpha);

        return JAI.create("Composite", pb, hints);
    }

    /**
     * Composites two images based on an alpha mask.
     *
     * <p>Creates a <code>ParameterBlockJAI</code> from all supplied arguments except <code>hints</code> and invokes
     * {@link JAI#createRenderable(String,ParameterBlock,RenderingHints)}.
     *
     * @see JAI
     * @see ParameterBlockJAI
     * @see RenderableOp
     * @param source0 <code>RenderableImage</code> source 0.
     * @param source1 <code>RenderableImage</code> source 1.
     * @param source1Alpha The alpha image for the first source.
     * @param source2Alpha The alpha image for the second source. May be <code>null</code>.
     * @param alphaPremultiplied True if alpha has been premultiplied to both sources and the destination. May be <code>
     *     null</code>.
     * @param destAlpha Indicates if the destination image should include an extra alpha channel, and if so, should it
     *     be the first or last band. May be <code>null</code>.
     * @param hints The <code>RenderingHints</code> to use. May be <code>null</code>.
     * @return The <code>RenderableOp</code> destination.
     * @throws IllegalArgumentException if <code>source0</code> is <code>null</code>.
     * @throws IllegalArgumentException if <code>source1</code> is <code>null</code>.
     * @throws IllegalArgumentException if <code>source1Alpha</code> is <code>null</code>.
     */
    public static RenderableOp createRenderable(
            RenderableImage source0,
            RenderableImage source1,
            RenderableImage source1Alpha,
            RenderableImage source2Alpha,
            Boolean alphaPremultiplied,
            CompositeDestAlpha destAlpha,
            RenderingHints hints) {
        ParameterBlockJAI pb = new ParameterBlockJAI("Composite", RenderableRegistryMode.MODE_NAME);

        pb.setSource("source0", source0);
        pb.setSource("source1", source1);

        pb.setParameter("source1Alpha", source1Alpha);
        pb.setParameter("source2Alpha", source2Alpha);
        pb.setParameter("alphaPremultiplied", alphaPremultiplied);
        pb.setParameter("destAlpha", destAlpha);

        return JAI.createRenderable("Composite", pb, hints);
    }
}
